@opentelemetry/propagator-b3

What is @opentelemetry/propagator-b3?

The @opentelemetry/propagator-b3 npm package is used for B3 propagation format which is a convention for passing trace context information across service boundaries. It supports both single-header and multi-header encoding. This package is part of the OpenTelemetry project which provides a collection of tools, APIs, and SDKs to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) to help analyze a software's performance and behavior.

What are @opentelemetry/propagator-b3's main functionalities?

B3 Propagation

This feature allows the user to extract and inject B3 propagation headers. The B3Propagator can be set as the global propagator in OpenTelemetry.

const { B3Propagator } = require('@opentelemetry/propagator-b3');
const { propagation } = require('@opentelemetry/api');

// Use the B3Propagator for extracting and injecting
propagation.setGlobalPropagator(new B3Propagator());

B3 Multi-header Propagation

This feature supports the B3 multi-header propagation format, which uses multiple headers to transmit tracing information. It is useful when interacting with systems that expect B3 headers in multiple header format.

const { B3MultiPropagator } = require('@opentelemetry/propagator-b3');
const { propagation } = require('@opentelemetry/api');

// Use the B3MultiPropagator for extracting and injecting with multi-header support
propagation.setGlobalPropagator(new B3MultiPropagator());

Other packages similar to @opentelemetry/propagator-b3

jaeger-client

This package is a Node.js client for Jaeger, a distributed tracing system. It includes Jaeger Tracer which can report tracing information to a Jaeger agent or collector. Jaeger and B3 are both tracing propagation formats, but Jaeger is specific to the Jaeger tracing system, whereas B3 is a more general format used by systems like Zipkin.

zipkin

The Zipkin npm package is a library that interfaces with the Zipkin API for distributed tracing. Similar to B3, Zipkin uses B3 propagation headers for tracing across service boundaries. The Zipkin package provides more comprehensive features for interacting with Zipkin, while @opentelemetry/propagator-b3 focuses on the propagation aspect within the OpenTelemetry ecosystem.

lightstep-tracer

LightStep's tracer library for Node.js is designed to monitor the performance of distributed systems. It uses its own propagation format and is part of the LightStep ecosystem, which is a different distributed tracing solution compared to the B3 propagation used by @opentelemetry/propagator-b3.

README

OpenTelemetry Propagator B3

The OpenTelemetry b3 propagator package provides multiple propagator implementations for systems using the b3 context format. See the b3 specification for complete details.

B3 Formats

Single-Header Format:

b3: {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}

Multi-Header Format:

X-B3-TraceId: {TraceId}
X-B3-SpanId: {SpanId}
X-B3-ParentSpanId: {ParentSpanId}
X-B3-Sampled: {SamplingState}

• {TraceId}

  • Required
  • Encoded as 32 or 16 lower-hex characters
  • 16 character traceIds will be converted to 32 characters by left-padding with 0s to conform with the OpenTelemetry specification

• {SpanId}

  • Required
  • Encoded as 16 lower-hex characters

• {ParentSpanId}

  • Optional
  • Used to support the Zipkin functionality where the client and server spans that make up an HTTP request share the same id
  • Not propagated by this library

• {SamplingState} - Single-header

  • Optional
  • Valid values
    • 1 - Accept
    • 0 - Deny
    • d - Debug
    • Absent - Defer sampling decision

• {SamplingState} - Multi-header

  • Optional
  • Valid values
    • 1 - Accept
    • 0 - Deny

• {Flags} - Multi-header

  • Optional
  • Debug is encoded as X-B3-Flags: 1. Absent or any other value can be ignored. Debug implies an accept decision, so don't also send the X-B3-Sampled header.

B3 Propagation

The default B3Propagator implements b3 propagation according to the OpenTelemetry specification. It extracts b3 context from multi and single header encodings and injects context using the single-header b3 encoding by default. The inject encoding can be changed to multi-header via configuration. See the examples below.

B3 Single-Header Configuration

const api = require('@opentelemetry/api');
const { B3Propagator } = require('@opentelemetry/propagator-b3');

api.propagation.setGlobalPropagator(new B3Propagator());

B3 Multi-Header Configuration

const api = require('@opentelemetry/api');
const { B3Propagator } = require('@opentelemetry/propagator-b3');

api.propagation.setGlobalPropagator(
  new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER })
);

B3 Single and Multi-Header Configuration

The B3Propagator always extracts both the single and multi-header b3 encodings. If you need to inject both encodings this can accomplished using a composite propagator.

const api = require('@opentelemetry/api');
const { B3Propagator } = require('@opentelemetry/propagator-b3');
api.propagation.setGlobalPropagator(
  new CompositePropagator({
    propagators: [
      new B3Propagator(),
      new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER }),
    ],
  })
);

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.

Changelog

0.19.0

:boom: Breaking Change

• opentelemetry-core, opentelemetry-tracing
  • #2111 feat: handle OTEL_TRACES_SAMPLER env var (@jtmalinowski)
  • #2098 chore(env): update default value for span's attributes/links/events count #1675 (@vmarchaud)
• opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-semantic-conventions, opentelemetry-tracing, opentelemetry-web
  • #2083 feat: add semconv generator for semantic-conventions-package (@weyert)
• opentelemetry-core, opentelemetry-grpc-utils, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-node, opentelemetry-plugin-grpc-js, opentelemetry-plugin-grpc, opentelemetry-plugin-http, opentelemetry-plugin-https, opentelemetry-sdk-node, opentelemetry-web
  • #2081 remove plugins (@obecny)
• opentelemetry-api-metrics, opentelemetry-context-async-hooks, opentelemetry-context-zone-peer-dep, opentelemetry-core, opentelemetry-exporter-collector-grpc, opentelemetry-exporter-collector-proto, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger, opentelemetry-exporter-prometheus, opentelemetry-exporter-zipkin, opentelemetry-grpc-utils, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-metrics, opentelemetry-node, opentelemetry-plugin-grpc-js, opentelemetry-plugin-grpc, opentelemetry-plugin-http, opentelemetry-plugin-https, opentelemetry-propagator-b3, opentelemetry-propagator-jaeger, opentelemetry-resource-detector-aws, opentelemetry-resource-detector-gcp, opentelemetry-resources, opentelemetry-sdk-node, opentelemetry-shim-opentracing, opentelemetry-tracing, opentelemetry-web
  • #2074 chore: peer depend on API (@dyladan)
  • #2063 chore: update API dependency to 1.0.0-rc.0 (@dyladan)
• opentelemetry-core, opentelemetry-propagator-b3
  • #2054 refactor: simplify b3 options (@mwear)

:rocket: (Enhancement)

• opentelemetry-instrumentation
  • #2135 fix: add isEnabled to InstrumentationBase (@seemk)
• opentelemetry-semantic-conventions
  • #2115 feat: upgrade semantic conventions to v1.2.0 of spec (@weyert)
• opentelemetry-core, opentelemetry-exporter-zipkin
  • #2097 feat(zipkin): allow to configure url via environment #1675 (@vmarchaud)
• opentelemetry-exporter-zipkin
  • #2050 chore: adding interceptor for getting headers before each request (@obecny)
• opentelemetry-exporter-collector-grpc
  • #2092 Migrate exporter-collector-grpc to grpc-js (@obecny)
• opentelemetry-instrumentation-http
  • #2043 chore: avoid unneeded context.with in http instrumentation (@Flarna)
• opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-xml-http-request
  • #2061 chore: adding info to debug whenever headers are being skipped due to cors policy (@obecny)

:bug: (Bug Fix)

• opentelemetry-exporter-prometheus
  • #2121 fix: ensure the label names are sanitised (@weyert)
• opentelemetry-instrumentation
  • #2120 fix(instrumentation): support multiple module definitions with different versions (@seemk)
• opentelemetry-instrumentation-http, opentelemetry-tracing
  • #2105 fix: don't use spanId from invalid parent (@Flarna)
• opentelemetry-context-async-hooks
  • #2088 fix: correct removeAllListeners in case no event is passed (@Flarna)
• opentelemetry-resource-detector-aws
  • #2076 fix: await http response in AWS EKS detector (@vreynolds)
• opentelemetry-core, opentelemetry-propagator-b3, opentelemetry-propagator-jaeger
  • #2082 chore: do not inject span context when instrumentation is suppressed (@dyladan)
• opentelemetry-core
  • #2080 fix: do not inject invalid span context (@dyladan)
• opentelemetry-tracing
  • #2086 fix: exception.type should always be a string (@YanivD)
• opentelemetry-propagator-jaeger
  • #1986 fix(propagator-jaeger): zero pad extracted trace id to 32 characters (@sid-maddy)

:books: (Refine Doc)

• #2094 chore: fixing readme info (@obecny)
• #2051 Add opentelemetry.io docs (@austinlparker)

:house: (Internal)

• opentelemetry-exporter-collector-grpc, opentelemetry-metrics, opentelemetry-tracing
  • #1780 chore: no-floating-promises (@naseemkullah)
• opentelemetry-context-zone, opentelemetry-core, opentelemetry-exporter-collector-grpc, opentelemetry-exporter-collector-proto, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger, opentelemetry-exporter-prometheus, opentelemetry-exporter-zipkin, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-metrics, opentelemetry-node, opentelemetry-propagator-jaeger, opentelemetry-resource-detector-aws, opentelemetry-resource-detector-gcp, opentelemetry-resources, opentelemetry-sdk-node, opentelemetry-shim-opentracing, opentelemetry-tracing, opentelemetry-web
  • #2073 chore: pin own deps (@dyladan)

Committers: 15

• Anuraag Agrawal (@anuraaga)
• Austin Parker (@austinlparker)
• Bartlomiej Obecny (@obecny)
• Daniel Dyla (@dyladan)
• Gerhard Stöbich (@Flarna)
• Jakub Malinowski (@jtmalinowski)
• Matthew Wear (@mwear)
• Naseem (@naseemkullah)
• Niek Kruse (@niekert)
• Siddhesh Mhadnak (@sid-maddy)
• Siim Kallas (@seemk)
• Valentin Marchaud (@vmarchaud)
• Vera Reynolds (@vreynolds)
• Weyert de Boer (@weyert)
• Yaniv Davidi (@YanivD)